home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-STLport.exe / {app} / include / CEGUIWindowManager.h < prev    next >
C/C++ Source or Header  |  2005-11-16  |  13KB  |  398 lines
  1. /************************************************************************
  2.     filename:     CEGUIWindowManager.h
  3.     created:    21/2/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Defines the interface for the WindowManager object
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIWindowManager_h_
  27. #define _CEGUIWindowManager_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIString.h"
  31. #include "CEGUISingleton.h"
  32. #include "CEGUILogger.h"
  33. #include "CEGUIIteratorBase.h"
  34. #include <map>
  35. #include <vector>
  36.  
  37. #if defined(_MSC_VER)
  38. #    pragma warning(push)
  39. #    pragma warning(disable : 4275)
  40. #    pragma warning(disable : 4251)
  41. #endif
  42.  
  43.  
  44. // Start of CEGUI namespace section
  45. namespace CEGUI
  46. {
  47. /*!
  48. \brief
  49.     The WindowManager class describes an object that manages creation and lifetime of Window objects.
  50.  
  51.     The WindowManager is the means by which Window objects are created and destroyed.  For each sub-class
  52.     of Window that is to be created, there must exist a WindowFactory object which is registered with the
  53.     WindowFactoryManager.  Additionally, the WindowManager tracks every Window object created, and can be
  54.     used to access those Window objects by name.
  55. */
  56. class CEGUIEXPORT WindowManager : public Singleton <WindowManager>
  57. {
  58. public:
  59.     /*************************************************************************
  60.         Public static data
  61.     *************************************************************************/
  62.     static const String GeneratedWindowNameBase;      //!< Base name to use for generated window names.
  63.  
  64.     /*!
  65.     \brief
  66.         Function type that is used as a callback when loading layouts from XML; the function is called
  67.         for each Property element encountered.
  68.  
  69.     \param window
  70.         Window object that the property is to be applied to.
  71.  
  72.     \param propname
  73.         String holding the name of the property that is being set.
  74.  
  75.     \param propvalue
  76.         String holding the new value that will be applied to the property specified by /a propname.
  77.  
  78.     \param userdata
  79.         Some client code supplied data.
  80.  
  81.     \return
  82.         - true if the property should be set.
  83.         - false if the property should not be set,
  84.     */
  85.     typedef bool PropertyCallback(Window* window, String& propname, String& propvalue, void* userdata);
  86.     
  87.     /*************************************************************************
  88.         Construction and Destruction
  89.     *************************************************************************/
  90.     /*!
  91.     \brief
  92.         Constructs a new WindowManager object.
  93.  
  94.         NB: Client code should not create WindowManager objects - they are of limited use to you!  The
  95.         intended pattern of access is to get a pointer to the GUI system's WindowManager via the System
  96.         object, and use that.
  97.     */
  98.     WindowManager(void);
  99.  
  100.  
  101.     /*!
  102.     \brief
  103.         Destructor for WindowManager objects
  104.  
  105.         This will properly destry all remaining Window objects.  Note that WindowFactory objects will not
  106.         be destroyed (since they are owned by whoever created them).
  107.     */
  108.     ~WindowManager(void);
  109.  
  110.  
  111.     /*!
  112.     \brief
  113.         Return singleton WindowManager object
  114.  
  115.     \return
  116.         Singleton WindowManager object
  117.     */
  118.     static    WindowManager&    getSingleton(void);
  119.  
  120.  
  121.     /*!
  122.     \brief
  123.         Return pointer to singleton WindowManager object
  124.  
  125.     \return
  126.         Pointer to singleton WindowManager object
  127.     */
  128.     static    WindowManager*    getSingletonPtr(void);
  129.  
  130.  
  131.     /*************************************************************************
  132.         Window Related Methods
  133.     *************************************************************************/
  134.     /*!
  135.     \brief
  136.         Creates a new Window object of the specified type, and gives it the specified unique name.
  137.  
  138.     \param type
  139.         String that describes the type of Window to be created.  A valid WindowFactory for the specified type must be registered.
  140.  
  141.     \param name
  142.         String that holds a unique name that is to be given to the new window.  If this string is empty (""), a name
  143.         will be generated for the window.
  144.  
  145.     \return
  146.         Pointer to the newly created Window object.
  147.  
  148.     \exception    AlreadyExistsException        A Window object with the name \a name already exists.
  149.     \exception    UnknownObjectException        No WindowFactory is registered for \a type Window objects.
  150.     \exception    GenericException            Some other error occurred (Exception message has details).
  151.     */
  152.     Window*    createWindow(const String& type, const String& name = "");
  153.  
  154.  
  155.     /*!
  156.     \brief
  157.         Destroy the specified Window object.
  158.  
  159.     \param window
  160.         Pointer to the Window object to be destroyed.  If the \a window is null, or is not recognised, nothing happens.
  161.  
  162.     \return
  163.         Nothing
  164.  
  165.     \exception    InvalidRequestException        Can be thrown if the WindowFactory for \a window's object type was removed.
  166.     */
  167.     void    destroyWindow(Window* window);
  168.  
  169.  
  170.     /*!
  171.     \brief
  172.         Destroy the specified Window object.
  173.  
  174.     \param
  175.         window    String containing the name of the Window object to be destroyed.  If \a window is not recognised, nothing happens.
  176.  
  177.     \return
  178.         Nothing.
  179.  
  180.     \exception    InvalidRequestException        Can be thrown if the WindowFactory for \a window's object type was removed.
  181.     */
  182.     void    destroyWindow(const String& window);
  183.  
  184.  
  185.     /*!
  186.     \brief
  187.         Return a pointer to the specified Window object.
  188.  
  189.     \param name
  190.         String holding the name of the Window object to be returned.
  191.  
  192.     \return
  193.         Pointer to the Window object with the name \a name.
  194.  
  195.     \exception UnknownObjectException    No Window object with a name matching \a name was found.
  196.     */
  197.     Window*    getWindow(const String& name) const;
  198.  
  199.  
  200.     /*!
  201.     \brief
  202.         Examines the list of Window objects to see if one exists with the given name
  203.  
  204.     \param name
  205.         String holding the name of the Window object to look for.
  206.  
  207.     \return
  208.         true if a Window object was found with a name matching \a name.  false if no matching Window object was found.
  209.     */
  210.     bool    isWindowPresent(const String& name) const;
  211.  
  212.  
  213.     /*!
  214.     \brief
  215.         Destroys all Window objects within the system
  216.  
  217.     \return
  218.         Nothing.
  219.  
  220.     \exception    InvalidRequestException        Thrown if the WindowFactory for any Window object type has been removed.
  221.     */
  222.     void    destroyAllWindows(void);
  223.  
  224.  
  225.     /*!
  226.     \brief
  227.         Creates a set of windows (a Gui layout) from the information in the specified XML file.    
  228.  
  229.     \param filename
  230.         String object holding the filename of the XML file to be processed.
  231.  
  232.     \param name_prefix
  233.         String object holding the prefix that is to be used when creating the windows in the layout file, this
  234.         function allows a layout to be loaded multiple times without having name clashes.  Note that if you use
  235.         this facility, then all windows defined within the layout must have names assigned; you currently can not
  236.         use this feature in combination with automatically generated window names.
  237.  
  238.     \param resourceGroup
  239.         Resource group identifier to be passed to the resource provider when loading the layout file.
  240.  
  241.     \param callback
  242.         PropertyCallback function to be called for each Property element loaded from the layout.  This is
  243.         called prior to the property value being applied to the window enabling client code manipulation of
  244.         properties.
  245.  
  246.     \param userdata
  247.         Client code data pointer passed to the PropertyCallback function.
  248.  
  249.     \return
  250.         Pointer to the root Window object defined in the layout.
  251.  
  252.     \exception FileIOException            thrown if something goes wrong while processing the file \a filename.
  253.     \exception InvalidRequestException    thrown if \a filename appears to be invalid.
  254.     */
  255.     Window*    loadWindowLayout(const String& filename, const String& name_prefix = "", const String& resourceGroup = "", PropertyCallback* callback = NULL, void* userdata = NULL);
  256.  
  257.     /*!
  258.     \brief
  259.         Return whether the window dead pool is empty.
  260.  
  261.     \return
  262.         - true if there are no windows in the dead pool.
  263.         - false if the dead pool contains >=1 window awaiting destruction.
  264.     */
  265.     bool isDeadPoolEmpty(void) const;
  266.  
  267.     /*!
  268.     \brief
  269.         Permanently destroys any windows placed in the dead pool.
  270.  
  271.     \note
  272.         It is probably not a good idea to call this from a Window based event handler
  273.         if the specific window has been or is being destroyed.
  274.  
  275.     \return
  276.         Nothing.
  277.     */
  278.     void cleanDeadPool(void);
  279.  
  280.     /*!
  281.     \brief
  282.         Writes a full XML window layout, starting at the given Window to the given OutStream.
  283.  
  284.     \param window
  285.         Window object to become the root of the layout.
  286.  
  287.     \param out_stream
  288.         OutStream (std::ostream based) object where data is to be sent.
  289.  
  290.     \param writeParent
  291.         If the starting window has a parent window, specifies whether to write the parent name into
  292.         the Parent attribute of the GUILayout XML element.
  293.  
  294.     \return
  295.         Nothing.
  296.     */
  297.     void writeWindowLayoutToStream(const Window& window, OutStream& out_stream, bool writeParent = false) const;
  298.  
  299.     /*!
  300.     \brief
  301.         Writes a full XML window layout, starting at the given Window to the given OutStream.
  302.  
  303.     \param window
  304.         String holding the name of the Window object to become the root of the layout.
  305.  
  306.     \param out_stream
  307.         OutStream (std::ostream based) object where data is to be sent.
  308.  
  309.     \param writeParent
  310.         If the starting window has a parent window, specifies whether to write the parent name into
  311.         the Parent attribute of the GUILayout XML element.
  312.  
  313.     \return
  314.         Nothing.
  315.     */
  316.     void writeWindowLayoutToStream(const String& window, OutStream& out_stream, bool writeParent = false) const;
  317.  
  318.     /*!
  319.     \brief
  320.         Rename a window.
  321.  
  322.     \param window
  323.         String holding the current name of the window to be renamed.
  324.  
  325.     \param new_name
  326.         String holding the new name for the window
  327.  
  328.     \exception UnknownObjectException
  329.         thrown if \a window is not known in the system.
  330.  
  331.     \exception AlreadyExistsException
  332.         thrown if a Window named \a new_name already exists.
  333.     */
  334.     void renameWindow(const String& window, const String& new_name);
  335.  
  336.     /*!
  337.     \brief
  338.         Rename a window.
  339.  
  340.     \param window
  341.         Pointer to the window to be renamed.
  342.  
  343.     \param new_name
  344.         String holding the new name for the window
  345.  
  346.     \exception AlreadyExistsException
  347.         thrown if a Window named \a new_name already exists.
  348.     */
  349.     void renameWindow(Window* window, const String& new_name);
  350.  
  351. private:
  352.     /*************************************************************************
  353.         Implementation Methods
  354.     *************************************************************************/
  355.     /*!
  356.     \brief
  357.         Implementation method to generate a unique name to use for a window.
  358.     */
  359.     String generateUniqueWindowName();
  360.  
  361.     /*************************************************************************
  362.         Implementation Constants
  363.     *************************************************************************/
  364.     static const char    GUILayoutSchemaName[];            //!< Filename of the XML schema used for validating GUILayout files.
  365.  
  366.  
  367.     /*************************************************************************
  368.         Implementation Data
  369.     *************************************************************************/
  370.     typedef std::map<String, Window*>            WindowRegistry;                //!< Type used to implement registry of Window objects
  371.     typedef std::vector<Window*>    WindowVector;   //!< Type to use for a collection of Window pointers.
  372.  
  373.     WindowRegistry            d_windowRegistry;            //!< The container that forms the Window registry
  374.     WindowVector    d_deathrow;     //!< Collection of 'destroyed' windows.
  375.  
  376.     unsigned long   d_uid_counter;  //!< Counter used to generate unique window names.
  377.  
  378. public:
  379.     /*************************************************************************
  380.         Iterator stuff
  381.     *************************************************************************/
  382.     typedef    ConstBaseIterator<WindowRegistry>    WindowIterator;
  383.  
  384.     /*!
  385.     \brief
  386.         Return a WindowManager::WindowIterator object to iterate over the currently defined Windows.
  387.     */
  388.     WindowIterator    getIterator(void) const;
  389. };
  390.  
  391. } // End of  CEGUI namespace section
  392.  
  393. #if defined(_MSC_VER)
  394. #    pragma warning(pop)
  395. #endif
  396.  
  397. #endif    // end of guard _CEGUIWindowManager_h_
  398.